Release 10.1A: OpenEdge Development:
Progress 4GL Reference

AUTHENTICATION-FAILED( ) method

Indicates that an unsealed Client-principal object could not be authenticated. This authentication failure signifies that the application or database user identity from the registered authentication domain is not authentic. Once invalidated, the Client-principal object’s properties cannot be changed and the object cannot be sealed.

Note: An application can use this method to invalidate an unsealed Client-principal object for any reason.

Return type: LOGICAL

Applies to: Client-principal object handle

Syntax

AUTHENTICATION-FAILED( [ reason ] )

reason

An optional character expression that specifies the reason for the authentication failure. For example, “Invalid user name or password”. Progress sets the STATE-DETAIL attribute to this value.

If you call this method for a sealed Client-principal object, Progress generates a run-time error.

If successful, this method returns TRUE. Otherwise, it returns FALSE.

Calling this method generates an audit event and creates an audit record for the event in all connected audit-enabled databases according to each database’s current audit policy settings.

Progress also sets the LOGIN-STATE attribute for the Client-principal object to “FAILED”.

Use the LOGOUT( ) method to invalidate, or terminate access to, a sealed Client-principal object.

Example

The following code fragment illustrates how to use the AUTHENTICATION-FAILED( ) method:

DEF VAR hCP as HANDLE. DEF VAR val-ok as LOGICAL. . . . CREATE CLIENT-PRINCIPAL hCp. . . . val-ok = hCP:AUTHENTICATION-FAILED(“Invalid username or password”).

See also

LOGIN-STATE attribute, LOGOUT( ) method, STATE-DETAIL attribute